A Driver for the NS16550 
DUART Which Runs on an 
NS32GX32 CPU 



1.0 INTRODUCTION 

This application note supplies a software program which 
serves as a driver for the NS1 6550 DUART. The driver runs 
on the NS32GX32 CPU, and should run with no modifica- 
tions on all other Embedded System Processors. 
The driver is useful for anyone who is writing a monitor or 
system kernel which will run on a system with an 
NS32GX32 and NS16550. It is well documented and can be 
modified according to the user's needs. 
Drivers of this sort are hard to develop, since they are very 
hard to debug. In order to debug such a driver there needs 
to be some sort of a communication line to the developed 
system. This line is used in order to load the driver into the 
memory of the developed system. But, in this case the com- 
munication line is controlled by the NS16550, which doesn't 
have a driver yet. 

The NS16550 is a popular standard DUART which has 2 
communication ports and is useful for serial I/O operations. 
It also contains a FIFO on each port allowing synchronous 
communication without losing data. 
The driver has the following features: 

— It controls both ports of the DUART. 

— It can be told to echo its input, and if CR should be ech- 
oed as GRLF. Echoing is a required feature by many sys- 
tems. 

— It can be told to ignore echo of its output, and if CR is 
echoed as CRLF. 

— It can be told to treat 'S (XOFF), '0 (XON) and 'H (Back- 
space). These control characters are the standard com- 
munication signals to pause and restart communication 
('S and 'Q respectively), and to erase the last character 
sent CH). 

— It can be told to wait until input arrives or only till a speci- 
fied timeout has passed. These are the two popular 
modes of operation in communication systems. 

— It can read/write a single character or a whole line. 

— It can be told to read a specified number of characters or 
till a CR (and return the length). 

The driver is designed for synchronous communication. 

The driver is written in a very portable way so that it can be 

transported to other Embedded System Processors with no 

modifications. 

It is compiled and linked by the GNX package supplied by 

NSC. 

2.0 USAGE 

The driver consists of 3 files: 

1. An assembler source file containing the initialization rou- 
tine (int_16550). 

2. A C source file containing the functions to read/write 
from/to the DUART. 
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3. A CPP include file used by both source files, defining 
global constants. These constants define the addresses 
of the DUART on the board and the requested baud rate. 
In addition the driver's makefile (for UNIX systems) is sup- 
plied, and a demo program which runs it. 
The user should perform the following steps in order to use 
the driver: 

1. Modify the include file to define the DUART address on 
his board. These are the lines: 

# define USART_0_ADDR < address of port 0> 

# define USART_1_ADDR < address of port 1 > 

2. Modify the include file to define the baud rate on his 
board. The baud rate is defined according to the 
NS16550 data sheet. For example: 12 signals 9600 baud 
at 1.8432 MHz crystal. This is the line: 

#define BAUD_RATE <baud rate> 

3. Modify the include file to define the timeout constant ac- 
cording to his needs. The read operations can be instruct- 
ed to wait for input. This constant defines the number of 
times a read will be attempted before a failure is reported 
in this mode. This is the line: 

#define IO_TIMEOUT <number of attempts> 

4. In his program he should add a call for the init 16550 

routine as one of the first things it does. This must, of 
course, come before any attempt to read or write from 
the NS16550. 

5. The driver uses 4 global vahables which should be initial- 
ized: 

world echo — Specifies if the world (the hardware on 

the other side of the communication 
line) echoes what it receives. 

world crif — Specifies if the world echoes a CR as 

CRLF. 

board echo — Specifies if the board (on which the 

driver and the NS16550 reside) should 
echo what it receives. 

board crIf — Specifies if the board should echo CR 

as CRLF. 
Each of these variables is a 2 element array, whose first 
element refers to port and the second to port 1 . A value 
of specifies FALSE and a value of 1 specifies TRUE. 

Example: world echo[0] = 0; 

This instruction informs the driver that the world 
echoes any character it receives from port 0. 

6. The user can call the following functions from his pro- 
gram: read line, write line, read char, write char. 

They are defined in the next section. 

7. Compile the driver (no special switches needed) and link 
it to his program. 

Note: If the user calls the Init 16550 function from a reset function (when 

there Is still no confidence that the memory Is operative), the function can be 
jumped to, and passed the return address In a register. The ret Instruction at 
the end of the function should be replaced by a jump 0(r7) for example. 
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3.0 INTERFACE 

The interface to the driver is done via calls to a set of func- 
tions. Following is a description of each of these functions 
and its parameters. 

Note: The type 'str' is defined to be 'char"' 

1 . void read line (port, line, len, err); 

int port; 

str line, err; 

unsigned *len; 
Description: Reads a line from a port. 
Parameters: port — The port number (0 or 1 ) to be read from, 
line — A pointer to a character array in which 

the line read will be returned, 
len — The number of characters to be read. 

specifies to read until a CR. 
err — Contains an error message, if an error oc- 
curred during the read. If it is null, no error 
occurred. 

2. void write line (port, line); 

int port; 

str line; 
Description: Writes a line to a port. 

Parameters: port — The port number (0 or 1) to be written to. 
line — A pointer to a character array in which 
the line to be written is placed. The line 
should end with a CR. 



3. void read char (port, ch, wait, err); 

int port; 

char *ch; 

boolean wait; 
str err; 

Description: Reads a character from a port. 
Parameters: port — The port number (0 or 1) to be read from, 
ch — A pointer to a character in which the char- 
acter read will be returned, 
wait — If TRUE, will wait until a character ar- 
rives (if one is not present in the FIFO 
already). If FALSE, will attempt to read 

10 TIMEOUT times before giving up 

and returning an error, 
err — Contains an error message, if an error oc- 
curred during the read. If it is null, no error 
occurred. 

4. void write char (port, ch); 

int port; 

char ch; 
Description: Writes a character to a port. 
Parameters: port — The port number (0 or 1) to be read from, 
ch — A pointer to a character in which the char- 
acter to be written is at. 



4.0 THE FILES 

Attached are the source files. 

4.1 16550.h— The CPP Include File 



^* + *********jK******S 



* 16550 definitions 

* This module contains the CPP constants definitions for the 16550 driver. 

/* 

* Useful characters 

*/ 

♦define CR ' \r ' 

♦define LF '\n' 

♦define CTRL._Q '\021' 

♦define CTRL_S '\023' 

♦define CTRL_H '\010' 

/. 

* Maximum line size 

»/ 

♦define LINE_SIZE 270 

/» 

* The DSART addresses on the board. 

* NOTE: These addresses should be modified by the user to the addresses on 

* the tested board. 

*/ 

♦define USART_0_ADDR OxFOOOOO 
♦define DSAET_1_ADDR OxFOOOOS 

/* 

* The maximuin time to wait for character read (number of tries). 

•/ 

♦define lO.TIMEOUT ((int) 0x90000) 

/» 

* The baud rate as defined in the NS16550 data sheet . 

* (12 signals 9600 baud at 1.8432 MHz crystal) 

* NOTE: The baud rate should be modified by the user to fit his needs. 

*/ 

♦define BAUD^RATE 12 
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4.2 16550 asm.s — The Assembly File 




^*«******!t!**** 


********************** 


****************************************** 


* 
# 
♦ 

* This file CO 
# 

# Note that CO 


16550 


_asm . s 


ntains the init_16550 


routine. 


mment lines must begin 


with a blank so opp will disregard 


* them. 

♦ 






********************** 


****************************************** 


♦include "16550 


.h" 




.set 


usrtO, USART 0_ADDR 


# usrtO start address 


.set 


usrtl, USART 1 ADDR 


♦ usrtl start address 


.set 


ier, 1 


♦ interrupt enable register (IER) 


.set 


ffc, 2 


♦ fifo control register (FOR) 


.set 


com, 3 


# usrt line control register (LCR) 


. set 


modem, 4 


# modem control register (MCR) 


.set 


ck, 


# baud rate counter (DLL, DLM) 


.set 


Oke, 0x80 


# clock enable(dlab=l) 


.set 


modrl, OxS 


# async, 8bits, no parity, 1 stop bit 


.set 


modrS , 0x3 


♦ activate receive, transmit signals 


.set 


baud, BAUD_RATE 


# the baud rate 


# 

# 
♦ 
# 
♦ This is the 




Init_16550 


init routine for the NS16550 UART. 


* This routine 


must be written In as 


sembly. It doesn't use the RAM (or stack 


♦ since it is 


still RAM) , since it is usually called by the diagnostics 


# routine. For 


this reason you would 


usually like to jump to it directly 


♦ and have it 


jump back. A register 


can be used to contain the return address . 


♦ The baud rate (in the format requested by the UAET) can be passed as a 


# parameter in 


R6 instead of being loaded directly. 


# The only reg 

* 


ister used by this routine is R6. 


# 

_lnlt_16550: : 






movb 


$cke , ©usrtO+com 


# enable clock divisor accsess 


movb 


$cke,@usrtl+com 


# same for usrtl 


mow 


$baud , @usrtO+ck 


# set baud rate 


movw 


$baud,®usrtl+ck 




movw 


©usrtO+ck, r6 




movb 


$modrl , @usrtO+com 


# init line mode register 


movb 


$modrl , ©usrtl+com 




movqb 


0,®usrtO+ier 


# disable interrupts 


movqb 


0,@usrtl+ier 




movqb 


3,®usrt0+ffc 


# clear fifo 


movqb 


3,@usrtl+ffo 




movqb 


l,eusrtO+ffc 


# enable fifo 


movqb 


1 ,eusrtl+ffc 




movb 


$modr2 , ©usrtO+modem 


# activate receive transmit 


movb 


$modr2 , @usrt 1+modem 




ret 







# jump 


0(r7) 


# suggested return via register 
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4.3 16550.C— The Driver Itself 



t******!):****************^ 



I: ******* a 



* 16550_driver 

♦ Tlixs module contains a serial I/O driver for th.e NS16550. 

* Throughout this source, "world" refers to the outer world, "board" refers to 

• the board running this program . 



<**************** 



(!******************************************/ 



♦include < strings. h> 
♦include " 16550. h" 



Constants definition 



• Bit macroes 



♦define BIT_ON(bit, reg) ((boolean) (((reg) S (unsigned) (1 << (bit))) !- 0)) 
♦define BIT_OFF(bit, reg) ((boolean) (((reg) S (unsigned) (1 << (bit))) ~ 0)) 



/» 



• Boolean operators 



♦define HOT ! 
♦define AND m 
♦define OR i 



/« 



Types definition 



typedef unsigned char byte; 

typedef char *str; 

typedef char l_str[LINE_SIZE] ; 

typedef en\un { 

FALSE , 

TRUE 
} boolean; 
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Communioations control boolean variables, per port. 



cliar world_eclio[2] , 
world^crlf [2] , 
board_eclio[2] , 
board_crlf [2] ; 



/* The world eolioes wliat it receives */ 

/* The world echoes a CR as CRLF */ 

/* The board should echo what it receives */ 

I* The board should echo CR as CRLF */ 



/> 



* The structure of the NS16550 register file. Note that in case of a collision 
between two registers, the first register is defined here and the second 
register is defined to be the same. 



typedef volatile struct 



byte 


iop; 


byte 


ier ; 


byte 


for; 


byte 


Icr; 


byte 


mcr ; 


byte 


Isr; 


byte 


msr ; 


byte 


scr; 


} uart_regB_type ; 


♦define iir 


for 


♦define dll 


iop 


♦define dim 


ier 



/* Receive /Transmit register 

/« Interrupt enable register 

/• Fifo control register 

/* Line control register 

/» Modem control register 

/* Line status register 

/* Modem status register 

/* Scratch register 



/ * Interrupt ident register 
/* Divisor latch LSB (dlab-1) 
/* Divisor latch MSB (dlab-1) 



(RBR, THR) 


./ 


(IER) 


*/ 


(FOR) 


*/ 


(LCR) 


•/ 


(MCR) 


*/ 


(LSR) 


*/ 


(MSR) 


♦/ 


(SCR) 


./ 


(IIR) 


*/ 


(DLL) 


•/ 


(DLM) 


«/ 



Frequently used bits of different registers. 



♦define ODT.READY 5 
♦define IN_READy 

♦define PORT_0_STATUS 
♦define PORT_0_IO 
♦define P0RT_1_STATDS 
♦define P0RT_1_I0 



/* Transmit ready bit of LSRx 
/* Receive ready bit of LSRx 



uart_0_regs- > Isr 
uart_0_regs- > iop 
uart_l_regs- > Isr 
uart_l_regs- > iop 



/» 



The USART registers are memory napped to structures. 



static uart_regs_type 
static uart_regs_type 



*uart_0_regs 
""uart_l_regs 



(uart_regs_type •) USART_0_ADDR ; 
(uart_regs_type *) nSART_l_ADDR ; 
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Functions definition 



void read_line (/* port, line, len, err »/); 

void write_line (/* port, line */); 

void read_cliar (/» port, eh, wait, err */); 

void write_ohar (/* port, ch */); 

static boolean get_oliar(/* eh, status, io_port, wait, err */); 

static void get_liiie (/* port, line, len, err */); 



* Read_oharCport , ch, wait, err) 

* 

* This function reads one character from the port specified. 

* "S and 'Q will be treated appropriately. 

* If wait is FALSE an error will be signaled if a character doesn't arrive 

* before timeout . 

* If the board should echo the input, this function does it. 



void read_char(port , ch, wait, err) 

int port ; 

char * ch ; 

boolean wait ; 

str err; 
) 

boolean Gh_ok; 

volatile byte 'status, *io_port; 

/* 
* Set pointers according to port 



if (port == 0) { 

status = ^PORT_0_STATUS ; 

io_port = HPORT_0_IO; 
) 
else { 

status = SPORT.l.STATaS ; 

io_port - 6?PORT_1_IO; 



/* 
* Loop until we have a good character 

•/ 

ch_ok = FALSE; 
while (NOT ch_ok) { 

ch_ok - get_ohar(ch, status, io_port , wait, err); 

if (err[0] != '\0') { 
return; 

} 



} 
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* Echo the character if needed, 

V 

if (l)oard_eoho[port] ) { 

write_char(port , *ch); 

if ((»ch »- CR) AND (board_crlf [port] )) { 

write_ohar(port , LF); 
} 



/ * read_char * / 



* Get_ohar(ch, status, io_port, wait, err) 

* 

* This function reads and processes a character. The ports stauts register 

* and io_port are used. 

* The function returns TRUE if the character is ok. 



static boolean get_char(ch, status, io_port , wait, err) 

volatile byte 'status, •io_port; 

char *ch; 

boolean wait ; 

str err; 
( 

int i; 

/• 
* Wait until we are flagged that a character arrived. 

•/ 

if (wait) { 

while (BIT_OFF(IN_READY, » status)) { 
) 
} 
else { 

for (i = 0; i < lO^TIMEODT; i++) { 
if (BIT_ON(IN_READY, 'status)) { 

break ; 
) 
) 
if (i == IO_TIMEOUT) { 

strcpyCerr, " ERR TIMEOUT ") ; 
return (FALSE) ; 



• Read the character. 

./ 

*ch - *io_port; 
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* If it is a "Q. ignore it. 
*/ 

if Cch == CTRL_Q) { 
return(FALSE) ; 

} 

/» 

* If the character is a "S, keep reading until a *Q arrives. 

* Ignore timeout . 

' If the character is not a 'S, signal that it is ok. 

./ 

if Cch -= GTRL_S) { 

while (»ch != CTRL_(5) { 

while (BIT_OFF(IN_READY, *Etatus)) { 
} 

*eh - *lo_port; 
} 

return(FALSE); 
) 

return(TRUE) ; 

) /* get^ohar */ 

/» 

* Write_char(port , oh) 

* This function writes one character to the port specified. 

* If the world echoes the characters, this function rereads the character. 



void wrlte_ohar(port , ch) 
int port ; 
char ch ; 



{ 



volatile byte 'status, *io_port; 

char temp; 

l_str temp_message ; 

/. 

» Set pointers according to port 

«/ 

if (port — 0) { 

status = SPORT_0_STATaS ; 

io_port = SPORT_0_IO; 
} 
else { 

status = SPORT_l_STATDS ; 
io_port - 5rP0RT_l_I0; 

} 
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/* 

* Check if there is a character waiting on the input port. 

* If there is, and it is a "S, keep reading until a "Q is read. 

* Otherwise, ignore it. 

*/ 

if (BIT_ON(IN_READy, 'status)) { 
temp = *io_port: 
if (temp == CTRL_S) { 

while (temp !- CTRL_CJ) { 

while (BIT_OFF(IN_READY, 'status)) { 
) 

temp - *io_port; 
} 
) 
} 

/* 

* Write the character. 

*/ 

while (BIT_OFF(OnT_READy, 'status)) { 

} 

*io_port - ch; 

/« 

* If the world echoes the character, reread it. 

•/ 

if (world_echo[port] ) { 

read_char(port , Stemp, FALSE, temp_message) ; 

if ((ch == CR) AND (world_orlf)) { 

read_char(port , Stemp, FALSE, temp_message) ; 

) 
} 

) / * write_char * / 

/» 

* Read_line(port , line, len, err) 
* 

* This function controls the reading of a line from the requested port. 

* len = specifies that the reading should continue till a CR is reached. 
» It returns the line and the port from which the command was read. 



void read_line(port , line, len, err) 

int port ; 

str line, err; 

unsigned *len; 
{ 

errlO] = '\0' ; 
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/* 
* Keep trying to read a line, until success. 
*/ 

get_line(port , line, len, err); 

while (err[0] I- '\0') { 
write_line(port , err); 
get_linG(port , line, len, err); 



} /» read_line */ 

/• 

* 

* Get_line(port , line, len, err) 



* This function reads a line from the port specified. 

* Length - specifies that read should continue to a CR. 

* In any case, no more characters than the size of line are read. 

* Upon return, length will contain the number of characters read. 



»/ 



static void get_line(port , line, len, err) 

int port ; 

str line, err; 

unsigned 'len; 
{ 

boolean stop_on_cr, wait; 

char ch ; 

int i; 

/» 
• Check the length specified. 

»/ 

stop_on_cr = FALSE; 
if (*len == 0) { 

stop_on_cr - TRUE; 

*len - LINE_SIZE; 



/* 
* Read the line. Treat backspace ("H) on the way. 
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line[0] = '\0'; 
for (i = 0; i < *len ; i++) { 
if (i == 0) { 

wait - TRDE; 
} 
else { 

wait = FALSE; 
> 

read_char(port , Soh, wait, err); 
if (errCO] !- '\0') { 
* len - i ; 
return; 
} 

if (oh -= CTRL_H) { 
if (i . 0) { 
i -= 2; 

if (board_echo[port] ) { 
write_char(port , ch); 
write_cliar(port , ' '); 
write_cliar(port , ch); 
} 

continue ; 
} 

continue ; 
} 

if ((ch — CR) AND (stop_on_cr)) { 
line[i] - '\0'; 
'len = i; 
return ; 
} 

line[i] - ch; 
) 

} /* get_line */ 

/• 

* Wrlte_line(port , line) 

• This function writes a line to the requested communication port . 



void write_line(port , line) 

int port ; 
str line; 
{ 

int i; 

for (i - 0; i < strlen(line) ; i++) { 

write_char(port , llneli]); 
} 

write_char(port , CR) ; 

) / * write_line * / 
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4.4 demo.c — The Demo Program 

* 

' 16550_demo 

* 

* This module contains an ezample of how to use the driver for the NS16550. 

* Throughout this source, "world" refers to the outer world, "board" refers to 

* the board running this program. 

**********♦***********#***#»***********«*****************♦*******************/ 

/* 

* Include the 16550 include file. 

*/ 

♦include " 16550. h" 

/* 

* Declare the used functions and global variables in the driver. 

*/ 

void read_line (/* port, line, len, response */); 
void write_lineC/* port, line */); 

char board_echo[2] , /♦ The board should echo what it receives */ 

board_Grlf [2] ; /» The board should echo OR as CRLF ♦/ 

main ( ) { 

static char ln[LINE_SIZE] , /* The line read/written */ 

resp[LINE_SIZE] ; /' The response (error message) •/ 

static unsigned len=0; /♦ The length of the line to be read */ 

/* 

* Call the drivers init routine and initialize. 

•/ 

init_16550(); 

board_echo[0] - 

board_crlf [0] = 

board_echo [ 1 ] - 

board_crlf [ 1 ] - 

/* 

* Write messages to port 0. 
*/ 

write_line(0, "hello worldXn"); 

write_llne(0, "This is the 16550 driver testXn"); 



TL/EE/10601-11 



13 



/* 

* Read a line from port 0, until a CR. 

»/ 

read_line(0, In, Slen, resp); 
if (respCO] !- '\0') exit(l); 
write_line(0, "line receivedXn" ) ; 
write_llne(0. In); 

/» 

* Ask the driver to echo all its input from port 0, and echo CR as CRLF. 
*/ 

l3oard_echo[0] - 1; 
board_crlf [0] - 1; 

/• 

* Read a line from port 0. Note that len contains the number of characters 

* read previously (and not 0), so the read will read the same number of 

* characters without reguarding CR. 

./ 

read_line(0. In, fflen, resp); 
if (respEO] ! ■= '\0') exit(l); 

/* 

* Ask the driver to stop echoing CR as CRLF in port 0, and read a line 

* until a CR. 

*/ 

board_crlf [0] = 0; 

len = 0; 

read_line(0, In, Slen, resp); 

if (respCOl != '\0') exit(l); 

/» 

* Write a line to port 1, and read an answer. 

*/ 

write_line(l , "hello port l\n"); 
len - 0; 

read_line(0, In, fflen, resp); 
if (respEO] != '\0') exit(l); 
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4.5 makefile — The Makefile 

* 

# This makefile compiles the 16550 driver with the demo program. 

# Type "maie" to produce the executable called "16550". 
# 

OBJS - demo.o 16530.0 

SOURCES - demo.c 16550. c 

H^DIR - . 

CC - nmcc 
AS - nasm -o 
CFLAGS = -KCGX32 -g 

16B50: 16550_asm.o $(OBJS) 16550. h 

$(CC) $(CFLAGS) -0 16550 16550_asm.o $(OBJS) 

demo . : demo . c 

16550.0: 16550. c 

16550_asm.O: 16550_asm.s 16550. h 

$(AS) -o 16550_asm.o $CAS_FLAG5) 16550_asm.s 
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LIFE SUPPORT POLICY 



NATIONAL'S PRODUCTS ARE NOT AUTHORIZED FOR USE AS CRITICAL COMPONENTS IN LIFE SUPPORT 
DEVICES OR SYSTEMS WITHOUT THE EXPRESS WRITTEN APPROVAL OF THE PRESIDENT OF NATIONAL 
SEMICONDUCTOR CORPORATION. As used herein: 



1. Life support devices or systems are devices or 2. A critical component Is any component of a 



life 



systems which, (a) are Intended for surgical Implant 
into the body, or (b) support or sustain life, and whose 
failure to perform, when properly used In accordance 
with Instructions for use provided in the labeling, can 
be reasonably expected to result In a significant Injury 
to the user. 



support device or system whose failure to perform can 
be reasonably expected to cause the failure of the life 
support device or system, or to affect Its safety or 
effectiveness. 
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